STRPARSE

NAME

SYNOPSIS

#include "str.h"

str_h str_parse( str, separ, flags, errnop )
char *str ;
char *separ ;
int flags ;
int *errnop ;

void str_endparse( handle )
str_h handle ;

char *str_component( handle )
str_h handle ;

int str_setstr( handle, newstr )
str_h handle ;
char *newstr ;

int str_separator( handle, separ )
str_h handle ;
char *separ ;

char *str_nextpos( handle )
str_h handle ;

extern int str_errno ;

DESCRIPTION

These functions are useful for parsing strings. In this context parsing means breaking the string into substrings. The substrings are separated by a list of possible separator characters.

str_component() returns successive substrings of the string. str_parse() creates and initializes a string parser with the string that will be processed, str, the list of possible separator characters, separ, and flags that control how the parser works. The flags argument is formed by ORing one or more of the following constants:

STR_RETURN_ERROR

If something goes wrong return a value that indicates that an error occured (e.g. out of memory). The default is for the program to be terminated with an appropriate error message.

STR_NULL_START

If str starts with a separator then a zero-length string will be returned the first time str_component() is called.

STR_NULL_END

If str starts with a separator then a zero-length string will be returned by str_component() when the substrings of str are exhausted.

STR_MALLOC

The strings returned by str_component() will be in malloc'ed memory. By default the substrings are part of str. If this option is not used str will be modified by str_component().

Finally, STR_NOFLAGS may be used to specify no flags. The errnop argument points to an integer where the string processing functions will deposit an error code if an error occurs. If errnop is NULL the error codes will be placed in str_errno. This is useful only if STR_RETURN_ERROR is used in flags. It is possible that str is NULL. In this case, a subsequent str_setstr() should be used to specify the string to be processed.

str_component() returns successive substrings from the string associated with the parser specified by handle.

str_endparse() destroys the parser specified by handle.

str_setstr() changes the processed string to newstr.

str_separator() replaces the list of separator characters with separ. Processing continues from the current position.

str_nextpos() returns a pointer to the rest of the string. The previous character is a separator character (if STR_MALLOC is not set, then the previous character is NUL ).  

RETURN VALUES

str_parse() returns a parser handle or NULL if something goes wrong and flags & STR_RETURN_ERROR is true. Possible str_errno values:

STR_ENULLSEPAR

separ is NULL

STR_ENOMEM

the program ran out of memory

str_component() returns a pointer to the next substring or NULL if something goes wrong and flags & STR_RETURN_ERROR is true.

str_setstr() returns STR_OK on success or STR_ERR on failure.

str_separator() returns STR_OK on success or STR_ERR on failure.

str_nextpos() returns a pointer or NULL if the end of string has been reached.  

BUGS

There should be only one parser active on a specific string. If there is more than one, they all must use the STR_MALLOC option.

Index

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

BUGS